% The Manifest Format
-# The `[package]` Section
+# The `[package]` section
The first section in a `Cargo.toml` is `[package]`.
All three of these fields are mandatory.
-## The `version` Field
+## The `version` field
Cargo bakes in the concept of [Semantic
Versioning](http://semver.org/), so make sure you follow some basic rules:
traits, fields, types, functions, methods or anything else.
* Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
-## The `build` Field (optional)
+## The `build` field (optional)
This field specifies a file in the repository which is a [build script][1] for
building native code. More information can be found in the build script
build = "build.rs"
```
-## The `exclude` and `include` Fields (optional)
+## The `exclude` and `include` fields (optional)
You can explicitly specify to Cargo that a set of [globs][globs] should be
ignored or included for the purposes of packaging and rebuilding a package. The
[globs]: http://doc.rust-lang.org/glob/glob/struct.Pattern.html
-## The `publish` Field (optional)
+## The `publish` field (optional)
The `publish` field can be used to prevent a package from being published to a
repository by mistake.
publish = false
```
-## The `workspace` Field (optional)
+## The `workspace` field (optional)
The `workspace` field can be used to configure the workspace that this package
will be a member of. If not specified this will be inferred as the first
For more information, see the documentation for the workspace table below.
-## Package Metadata
+## Package metadata
There are a number of optional metadata fields also accepted under the
`[package]` section:
search ranking of a crate. It is highly discouraged to omit everything in a
published crate.
-## The `metadata` Table (optional)
+## The `metadata` table (optional)
Cargo by default will warn about unused keys in `Cargo.toml` to assist in
detecting typos and such. The `package.metadata` table, however, is completely
assets = "path/to/static"
```
-# Dependency Sections
+# Dependency sections
See the [specifying dependencies page](specifying-dependencies.html) for
information on the `[dependencies]`, `[dev-dependencies]`, and target-specific
`[target.*.dependencies]` sections.
-# The `[profile.*]` Sections
+# The `[profile.*]` sections
Cargo supports custom configuration of how rustc is invoked through profiles at
the top level. Any manifest may declare a profile, but only the top level
panic = 'unwind'
```
-# The `[features]` Section
+# The `[features]` section
Cargo supports features to allow expression of:
optional dependencies. This allows packages to internally enable/disable
features without requiring a new dependency.
-## Usage in End Products
+## Usage in end products
One major use-case for this feature is specifying optional features in
end-products. For example, the Servo project may want to include optional
Default features could be excluded using `--no-default-features`.
-## Usage in Packages
+## Usage in packages
In most cases, the concept of *optional dependency* in a library is best
expressed as a separate package that the top-level application depends on.
high-level packages that are designed for curation. If a feature is optional, it
can almost certainly be expressed as a separate package.
-# The `[workspace]` Section
+# The `[workspace]` section
Projects can define a workspace which is a set of crates that will all share the
same `Cargo.lock` and output directory. The `[workspace]` table can be defined
Most of the time workspaces will not need to be dealt with as `cargo new` and
`cargo init` will handle workspace configuration automatically.
-# The Project Layout
+# The project layout
If your project is an executable, name the main source file `src/main.rs`. If it
is a library, name the main source file `src/lib.rs`.
* compile and run your library’s [integration tests](#integration-tests); and
* compile your library’s examples.
-## Integration Tests
+## Integration tests
Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
Cargo will compile each of these files as a separate crate. The crate can link
the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
the test files.
-# Configuring a Target
+# Configuring a target
All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
sections support similar configuration for specifying how a target should be
harness = true
```
-# Building Dynamic or Static Libraries
+# Building dynamic or static libraries
If your project produces a library, you can specify which kind of library to
build by explicitly listing the library in your `Cargo.toml`:
% Package ID Specifications
-# Package ID Specifications
+# Package ID specifications
Subcommands of Cargo frequently need to refer to a particular package within a
dependency graph for various operations like updating, cleaning, building, etc.
Here, brackets indicate that the contents are optional.
-## Example Specifications
+## Example specifications
These could all be references to a package `foo` version `1.2.3` from the
registry at `crates.io`
| `crates.io/bar#foo:1.2.3` | foo | 1.2.3 | *://crates.io/bar |
| `http://crates.io/foo#1.2.3` | foo | 1.2.3 | http://crates.io/foo |
-## Brevity of Specifications
+## Brevity of specifications
The goal of this is to enable both succinct and exhaustive syntaxes for
referring to packages in a dependency graph. Ambiguous references may refer to
projects / cargo.git / commitdiff